package com.rolerealm.service;

import com.rolerealm.domain.dto.RecommendationRequestDTO;
import com.rolerealm.domain.vo.CharacterVO;
import com.rolerealm.domain.vo.PageResult;

import java.util.List;

/**
 * 推荐服务接口
 * 
 * @author RoleRealm Team
 * @version 1.0.0
 */
public interface RecommendationService {

    /**
     * 获取用户个性化角色推荐
     * 
     * @param userId 用户ID
     * @param page 页码
     * @param size 每页大小
     * @return 推荐角色分页列表
     */
    PageResult<CharacterVO> getRecommendedCharacters(Long userId, Integer page, Integer size);

    /**
     * 根据推荐请求获取推荐结果
     * 
     * @param request 推荐请求
     * @return 推荐角色列表
     */
    List<CharacterVO> getRecommendedCharacters(RecommendationRequestDTO request);

    /**
     * 获取热门角色推荐
     * 
     * @param limit 推荐数量
     * @return 推荐角色列表
     */
    List<CharacterVO> getPopularRecommendations(Integer limit);

    /**
     * 获取基于内容的推荐
     * 
     * @param userId 用户ID
     * @param limit 推荐数量
     * @return 推荐角色列表
     */
    List<CharacterVO> getContentBasedRecommendations(Long userId, Integer limit);

    /**
     * 获取基于技能的推荐
     * 
     * @param userId 用户ID
     * @param skillTypes 技能类型列表
     * @param limit 推荐数量
     * @return 推荐角色列表
     */
    List<CharacterVO> getSkillBasedRecommendations(Long userId, List<String> skillTypes, Integer limit);

    /**
     * 获取混合推荐结果
     * 
     * @param request 推荐请求
     * @return 推荐角色列表
     */
    List<CharacterVO> getHybridRecommendations(RecommendationRequestDTO request);

    /**
     * 刷新用户推荐结果
     * 
     * @param userId 用户ID
     */
    void refreshUserRecommendations(Long userId);

    /**
     * 清除用户推荐缓存
     * 
     * @param userId 用户ID
     */
    void clearUserRecommendations(Long userId);
}
